home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1994 August: Tool Chest / Dev.CD Aug 94.toast / Tool Chest / Games / Mac Game Developer's Handbook / Graphics / Gimmie Depth or Death / Gimmie Depth or Death
Encoding:
Text File  |  1993-04-22  |  21.5 KB  |  33 lines  |  [ONLN/HLX2]
  1. Gimmie Depth Or Gimmie Death
  2. (So You Want to be a Monitors Impersonator?)
  3. Devices    M.DV.MonitorDepth
  4. Revised by:    Guillermo Ortiz    June 1990
  5. Written by:    Guillermo Ortiz    April 1990
  6. This Technical Note describes two new system calls that allow an application to change the depth and flags for a given device and also check whether a device supports a particular depth and flags setting.  Apple provides these calls to give developers a better way to help users make changes when they consider it appropriate.  Abusive use of these calls is a sure way to guarantee that the Thought Police come after you to confiscate your Macintoshes, your stock of Mountain Dew®, and your Technical Notes binder.  This Note assumes familiarity with Inside Macintosh, Volume V, Graphics Devices.
  7. Changes since April 1990:  Corrected trap addresses and dispatch numbers in the SetDepth and GetDepth definitions.
  8. Historic Novella
  9. Since the introduction of the Macintosh II, developers have had the strong urge to change the depth of Macintosh screens under program control.  Developers often ask, “How can I change the depth from my application like the Monitors cdev does?”  The reasons for this question have varied from pure Macintosh hacking spirit to valid reasons to the lack of finding a good solution which would work regardless of the depth setting the user may choose.
  10. A poor scenario occurs when a developer wants to impose a certain depth and color or black and white setting because the application does not work well, if at all, with any other configuration.  The responses from DTS always include questions about what happens to the application when the system in use does not support this “optimal” configuration or when one monitor is set to the magic configuration, but others are not, or when the user brings the application to the front and it finds that the user has changed the setting to something with which it is not equipped to deal.
  11. On the other hand, DTS does see situations where an application that deals with certain image types may work better with a particular setting and would like to present the user with a dialog box similar to the Monitors cdev to allow the user to change the depth and color settings from within the application.
  12. Not everyone agrees on the wisdom of providing facilities for an application to allow users to change depth and color settings from within itself, but all agree that a well-behaved application (remembering that well-behaved applications are more likely to survive system and hardware changes) should only change depth and color settings in the following circumstances:
  13. •    Depth changes can only be made with the user’s consent; never change depths because it is simply convenient for the application.  The user paid for his system and if the user wants color, be prepared to give color.  If the user wants millions of colors, don’t change the display to one-bit black and white.
  14. •    The minimal amount of user input to change depth and color settings should be to provide a preferences dialog box where the user would be given a yes or no choice to change depths when a particular action is chosen.  The application should make the “no” choice the default and have a sensible mechanism for handling the situation when the user chooses no.
  15. •    Under no condition should an application change depth or color settings while in the background.  An application should only initiate depth or color changes when it is the frontmost application; do not twiddle with the user’s settings while in the background.
  16. The Calls
  17. Beginning with System Software 6.0.5 (regardless of whether or not 32-Bit QuickDraw is installed), applications can make a call to SetDepth to change the depth and flag settings for a given device.
  18. FUNCTION SetDepth(gd:GDHandle; newDepth,whichFlags, newFlags: Integer):Integer;
  19.     INLINE $203C,$000A, $0013,$AAA2; { Move.L #$000A0013,D0
  20.                                       _PMgrDispatch
  21.                                     }
  22. pascal short SetDepth(GDHandle gd, short  newDepth,short whichFlags, short newFlags)
  23.                       = {0x203C, 0x000A, 0x0013, 0xAAA2};
  24. Where gd is the device to be changed, newDepth is the desired depth (you can pass the bit depth or the mode necessary to set the requested depth,) whichFlags is a bit field selector specifying which bits in newFlags are meaningful, and newFlags are bits to be set in the gdFlags field of the device record as specified by whichFlags.  For example, if you want to set a depth of eight in black and white, the call would be as follows:
  25.         someResult := SetDepth(myGDevice,8,1,0);
  26. In this call, newDepth = 8 sets an eight-bit depth, whichFlags = 1 indicates that only bit one of newFlags is important, and newFlags = 0 clears the gdDevType flag in the device record (0 = monochrome, 1 = color).  SetDepth returns zero if successful or a non-zero value if it cannot impose the desired depth on the requested device.
  27. Also beginning with System Software 6.0.5, applications can make a call to HasDepth to verify if a given device supports a mode for the desired depth.
  28. FUNCTION HasDepth(gd:GDHandle; newDepth,whichFlags, newFlags: Integer):Integer;
  29.     INLINE $203C,$000A $0014,$AAA2; { Move.L #$000A0014,D0
  30.                                       _PMgrDispatch
  31.                                     }
  32. pascal short HasDepth(GDHandle gd, short  newDepth,short whichFlags, short newFlags)
  33.                       = {0x203C,0x000A 0x0014,0xAAA2};
  34. Where gd is the device to be verified, newDepth is the desired depth, whichFlags is a bit field selector specifying which bits in newFlags are meaningful, and newFlags are bits to be checked in the gdFlags field of the device record as specified by whichFlags.  HasDepth returns zero if the desired depth or flag setting is not supported on the given device; otherwise, HasDepth returns the mode necessary to set the device to the desired depth (which may be passed as the newDepth parameter in a call to SetDepth).
  35. Further Reference:
  36. •    Inside Macintosh, Volume V, Graphics Devices
  37. •    Designing Cards and Drivers for the Macintosh Family, Second Edition
  38. Mountain Dew is a registered trademark of Pepsico, Inc.
  39. *◊#ˇ ˇˇˇˇ#◊°d WORDS †å°d WORDR…†Ç 
  40. .ZÄ#
  41.     0Ià:µú9"z    ˇˇˇˇˇˇˇˇ#†ƒ°d
  42. ONLNf˛†å°d1drw2…-·_ġˇˇˇˇˇè°ñ x°ddrw2:°ddrw2:$°d4drw2:°öˇ˙ó@†ò,Times
  43. .WIQkWIQk+]ANew Technical Notes†ô°ddrw2:°„†ó°d1drw2eÙġˇˇˇˇˇP°ñ x°ddrw2:°ddrw2:$°d4drw2:°öˇ˚ÄE¿†ò
  44. !(zïDeveloper Support†ô°ddrw2:°„†ó°d`drw2-ÔˇˇˇˇˇˇKÔ- Z  eeZ°d1drw2 ¿˙ÈˇˇˇˇˇˇK°ñ x°ddrw2:°ddrw2:$°d4drw2:0°öˇÙĆò
  45. 0(TÔ†ô°ddrw2:°„†ó°d1drw2ÔÊ˙ˇˇˇˇˇˇ°ñ x°ddrw2:°ddrw2:$°d4drw2:    °öˇ˝Ä†ò
  46.     l+&    ®†ô°ddrw2:°„†ó°d1drw2Â-¯yˇˇˇˇˇˇ°ñ x°ddrw2:°ddrw2:$°d4drw2:°öˇ˚Ä%†ò
  47. BÄ(Y\    Macintosh†ô°ddrw2:°„†ó†ç°ddrw2D†É°dWORD†ç
  48. IR.°dONLNdz<å?(ßZGimmie Depth Or Gimmie Death°dONLNdå<û≠*,(So You Want to be a Monitors Impersonator?)
  49. °dONLNdJû<¨h*Devices°dONLNdRûr¨)6M.DV.MonitorDepth
  50. °dONLNdd∏<ƒs(‡Z Revised by:°dONLNdp∏уœ)HGuillermo Ortiz°dONLNdÄ∏Õƒ˛(‡Π   June 1990°dONLNdäƒ<–r(ÏZ Written by:°dONLNdñƒÑ–œ)HGuillermo Ortiz°dONLNd¶ƒÀ–˛(ÏÈ
  51. April 1990°dONLNd±‹<Ë°(ZThis Technical Note °dONLNd≈‹°Ë˛)eFdescribes two new system calls that allow an application to change the°dONLNd Ë<Ùá(Zdepth and flags °dONLNdËáÙ˛)KNfor a given device and also check whether a device supports a particular depth°dONLNdkÙ<°(ZOand flags setting.  Apple provides these calls to give developers a better way °dONLNd∫Ù°Δ(øto help °dONLNd¬ÙΔ·)%users°dONLNd«Ù·˛) make°dONLNdÕ< g((Zchanges °dONLNd’g ˛)+Owhen they consider it appropriate.  Abusive use of these calls is a sure way to°dONLNd% <Ω(4ZQguarantee that the Thought Police come after you to confiscate your Macintoshes, °dONLNdv Ω˛(4€
  52. your stock of°dONLNdÑ<$É(@Z Mountain Dew
  53.     °dONLNdêÉ#ä)G®
  54. °dONLNdëä$Ï), and your Technical °dONLNd¶Ï$·)b2Notes binder.  This Note assumes familiarity with °dONLNdÿ·$˛)ıInside°dONLNdfl$<0n(LZ    Macintosh°dONLNdË$n0˛)2, Volume V, Graphics Devices.°dONLNd0<<—(XZChanges since April 1990:°dONLNd0—<ÿ)ï °dONLNd 0ÿ<˛)5 Corrected trap addresses and dispatch numbers in the"O ,
  55. Courier°dONLNdV<<Lw(gZSetDepth°dONLNd^?wKé); and °dONLNdc<éL )GetDepth°dONLNdk? K)<
  56.  definitions."[ vXv
  57. °dONLNdyp<~ù(öZHistoric Novella
  58. °dONLNdää<ñ*ZSince the introduction of the Macintosh II, developers have had the strong urge to change °dONLNd‰äñ˛(≤the°dONLNdËñ<¢l(æZ>depth of Macintosh screens under program control.  Developers °dONLNd&ñl¢˛(æäoften ask, “How can I change°dONLNdC¢<Æh( Z<the depth from my application like the Monitors cdev does?” °dONLNd¢hÆ˛( Ü The reasons for this question°dONLNdûÆ<∫Ê(÷ZYhave varied from pure Macintosh hacking spirit to valid reasons to the lack of finding a °dONLNd˜ÆÊ∫˛(÷good°dONLNd¸∫<Δ≤(‚ZNsolution which would work regardless of the depth setting the user may choose.°dONLNdK“<fi£*HA poor scenario occurs when a developer wants to impose a certain depth °dONLNdì“£fi˛(˙¡and color or black°dONLNd¶fi<ÍS(Zand °dONLNd™fiSͲ)Swhite setting because the application does not work well, if at all, with any other°dONLNd˛Í<ˆ(ZVconfiguration.  The responses from DTS always include questions about what happens to °dONLNdTÍˆ˛(the°dONLNdXˆ<H(Z9application when the system in use does not support this °dONLNdëˆH˛(f#“optimal” configuration or when one°dONLNdµ<!(*Z/monitor is set to the magic configuration, but °dONLNd‰!˛)Â+others are not, or when the user brings the°dONLNd<í(6Zapplication to the °dONLNd#í˛)VJfront and it finds that the user has changed the setting to something with°dONLNdn<&—(BZ!which it is not equipped to deal.°dONLNdê2<>z*
  59. On the other °dONLNdù2z>˛)>Phand, DTS does see situations where an application that deals with certain image°dONLNdÓ><Jı(fZ(types may work better with a particular °dONLNd>ıJ˛)π8setting and would like to present the user with a dialog°dONLNdOJ<Vÿ(rZ!box similar to the Monitors cdev °dONLNdpJÿV˛)ú=to allow the user to change the depth and color settings from°dONLNdÆV<b£(~Zwithin the application. fiXfi
  61. *sIGimmie Depth Or Gimmie Death (So You Want to be a Monitors Impersonator?)(Ò1) of 3ˇ°¿Ù%%DSIDICT:_cv
  62. currentdict /bu known {bu}if
  63. userdict /_cv known not{userdict /_cv 30 dict put}if
  64. _cv begin
  65. /bdf{bind def}bind def
  66. currentscreen/cs exch def/ca exch def/cf exch def
  67. /setcmykcolor where{/setcmykcolor get /cvcmyk exch def}{/cvcmyk{1 sub 4 1 roll 3{3 index add neg dup 0 lt{pop 0}if 3 1 roll}repeat setrgbcolor pop}bdf }ifelse
  68. /ss{//cf //ca //cs setscreen}bdf
  69. /stg{ss setgray}bdf
  70. /strgb{ss setrgbcolor}bdf
  71. /stcmyk{ss cvcmyk}bdf
  72. /min1{dup 0 eq{pop 1}if}bdf
  73. end
  74. currentdict /bn known {bn}if
  75. †ø<◊#ˇ ˇˇˇˇ#◊ 
  76. IR,Times
  78. .+6,Macintosh Technical Notes .4.˘
  79. °dONLNd(-*Not °dONLNd-(⁄)Zeveryone agrees on the wisdom of providing facilities for an application to allow users to°dONLNd_(4à(P6change depth and color °dONLNdv(à4⁄)pJsettings from within itself, but all agree that a well-behaved application°dONLNd¡4@(\6,(remembering that well-behaved applications °dONLNdÌ4@⁄)ÿ.are more likely to survive system and hardware°dONLNd@L©(h6Tchanges) should only change depth and color settings in the following circumstances:°dONLNdqX*d.+•°dONLNdsX<dò)Depth changes can °dONLNdÖXòdØ)\only°dONLNdâXØd≤) °dONLNdäX≤d∂)4be made with the user’s consent; never change depths°dONLNdød<pq(åZDbecause it is simply convenient for the application.  The user paid °dONLNddqp∂(åèfor his system°dONLNdp<|7(òZ8and if the user wants color, be prepared to give color. °dONLNdJp7|∂)˚ If the user wants millions°dONLNdf|<à^(§Z?of colors, don’t change the display to one-bit black and white.°dONLNd¶î*†.(ºH•°dONLNd®î<†Î)$The minimal amount of user input to °dONLNdÃîΆ∂)Ø)change depth and color settings should be°dONLNdˆ†<¨n(»Z to provide °dONLNd†n¨∂)2Ba preferences dialog box where the user would be given a yes or no°dONLNdD¨<∏É(‘ZAchoice to change depths when a particular action is chosen.  The °dONLNdÖ¨É∏∂(‘° application°dONLNdë∏<ƒ—(‡Zshould make the “no” choice °dONLNd≠∏—ƒ∂)ï-the default and have a sensible mechanism for°dONLNd€ƒ<– (ÏZ0handling the situation when the user chooses no.°dONLNd ‹*Ë.(H•°dONLNd‹<Ë])Under °dONLNd‹]Ëj)!no°dONLNd‹jË∂)
  80. E condition should an application change depth or color settings while°dONLNd\Ë<Ùs(ZAin the background.  An application should only initiate depth or °dONLNdùËsÙ∂(ë
  81. color changes°dONLNd´Ù<ù(ZNwhen it is the frontmost application; do not twiddle with the user’s settings °dONLNd˘Ùù∂(ªwhile°dONLNdˇ< î((Zin the background.
  82. °dONLNd&Q(B6    The Calls
  83. °dONLNd2>\*?Beginning with System Software 6.0.5 (regardless of whether or °dONLNd[2\>⁄(Zznot 32-Bit QuickDraw is°dONLNdsAMŸ(i6,installed), applications can make a call to ,
  84. Courier°dONLNdü>ŸN)¡SetDepth°dONLNdßAM); °dONLNd®AM⁄))to change the depth and flag settings for°dONLNd“MY\(u6a given device.
  85.     °dONLNd‚ep£*OFUNCTION SetDepth(gd:GDHandle; newDepth,whichFlags, newFlags: Integer):Integer;"Ñ3    °dONLNd2oz?*
  86. ;    INLINE $203C,$000A, $0013,$AAA2; { Move.L #$000A0013,D0"é3    °dONLNdnyÑ*
  87. 3                                      _PMgrDispatch"ò3    °dONLNd¢Éé—*
  88. %                                    }"¢3    "¨3    °dONLNd»ó¢º*Tpascal short SetDepth(GDHandle gd, short  newDepth,short whichFlags, short newFlags)"∂3    °dONLNd°¨5*
  89. 9                      = {0x203C, 0x000A, 0x0013, 0xAAA2};"¿3    
  90. °dONLNdW∫Δ;*Where °dONLNd]∑;«K)#gd°dONLNd_∫KΔ–) is the device to be changed, °dONLNd}∑–«)ÖnewDepth°dONLNdÖ∫Δ1)B is the °dONLNdç∫1Δ⁄)#desired depth (you can pass the bit°dONLNd±…’+(Ò69depth or the mode necessary to set the requested depth,) °dONLNdÍΔ+÷t(ÒI
  91. whichFlags°dONLNdÙ…t’∂)I is a bit field °dONLNd…∂’⁄)Bselector°dONLNd
  92. ÿ‰ã(6specifying which bits in °dONLNd&’ãÂ…)snewFlags°dONLNd.ÿ…‰+)> are meaningful, and °dONLNdC’+Âi)bnewFlags°dONLNdKÿi‰})> are °dONLNdPÿ}‰⁄)bits to be set in the°dONLNdf‰ÙJ(6gdFlags°dONLNdmÁJÛ
  93. )2, field of the device record as specified by °dONLNdô‰
  94. ÙV)√
  95. whichFlags°dONLNd£ÁVÛ⁄)I.  For example, if you want°dONLNdøÛˇ_(6Ito set a depth of eight in black and white, the call would be as follows:°dONLNd        
  96. 0*        
  97.     °dONLNd     0¯)(someResult := SetDepth(myGDevice,8,1,0);
  98. °dONLNd    :$0N(L6In this call, °dONLNd    H!N1†)6 newDepth = °dONLNd    S!†1®)R8°dONLNd    T$®0) sets an eight-bit depth, °dONLNd    n!1)twhichFlags = 1°dONLNd    |$0⁄)c indicates that only°dONLNd    ë3?H([6 bit one of °dONLNd    ú0H@Ü)0newFlags°dONLNd    §3Ü?⁄)> is important, and °dONLNd    ∑0⁄@0)T newFlags = 0°dONLNd    √30?b)V  clears the °dONLNd    œ0b@®)2    gdDevType°dONLNd    ÿ3®?Ã)F     flag in °dONLNd    ·3Ã?⁄)$the°dONLNd    ÂBNf(j6device record (0 °dONLNd    ˆBfNÒ)N= monochrome, 1 = color).  °dONLNd
  99. ?ÒO,)ãSetDepth°dONLNd
  100. B,N÷);$ returns zero if successful or a non°dONLNd
  101. =B÷N⁄)™-°dONLNd
  102. >NZg(v6Izero value if it cannot impose the desired depth on the requested device. fi4fi˘
  104. *{2) of 3)xIGimmie Depth Or Gimmie Death (So You Want to be a Monitors Impersonator?)ˇ Ä◊#ˇ ˇˇˇˇ#◊ 
  105. IR,Times
  107. .+Z,Developer Technical Support(,Û    June 1990 .X.
  108. °dONLNd<+»(GZAlso beginning with System °dONLNd»+≥)å0Software 6.0.5, applications can make a call to ,
  109. Courier°dONLNdK≥,)ÎHasDepth°dONLNdS+˛)= to°dONLNdW+<7](SZ?verify if a given device supports a mode for the desired depth.
  110.     °dONLNdóC<N«*OFUNCTION HasDepth(gd:GDHandle; newDepth,whichFlags, newFlags: Integer):Integer;"b    °dONLNdÁM<X^*
  111. :    INLINE $203C,$000A $0014,$AAA2; { Move.L #$000A0014,D0"l    °dONLNd"W<b;*
  112. 3                                      _PMgrDispatch"v    °dONLNdVa<lı*
  113. %                                    }"Ä    "ä    °dONLNd|u<ć*Tpascal short HasDepth(GDHandle gd, short  newDepth,short whichFlags, short newFlags)"î    °dONLNd—<äJ*
  114. 6                      = {0x203C,0x000A 0x0014,0xAAA2};"û    
  115. °dONLNdò<§_*Where °dONLNdï_•o)#gd°dONLNdòo§r) °dONLNdòr§ˆ)is the device to be verified, °dONLNd/8)ÑnewDepth°dONLNd7ò8§†)B is the desired depth, °dONLNdNÈ)h
  116. whichFlags°dONLNdXòȧ˛)I is a°dONLNd^ß<≥˜(œZ)bit field selector specifying which bits °dONLNdáߘ≥)ªin °dONLNd䧥C)newFlags°dONLNdíßC≥≠)> are meaningful, and °dONLNdߧ≠¥Î)jnewFlags°dONLNdØßÎ≥˛)> are°dONLNd¥∂<¬\(fiZbits to °dONLNdº∂\¬¥) be checked in the °dONLNdŒ≥¥√Ê)XgdFlags°dONLNd’∂ʬ≤)2, field of the device record as specified by °dONLNd≥≤√˚)Ã
  117. whichFlags°dONLNd ∂˚¬˛)I.°dONLNd¬<“y(ÌZHasDepth°dONLNd≈y—Â)=K returns zero if the desired depth or flag setting is not supported on the °dONLNda≈—˛(Ìgiven°dONLNdg‘<‡ì(¸Zdevice; otherwise, °dONLNdz—ì·–)WHasDepth°dONLNdÇ‘–‡ )=
  118.  returns the °dONLNdè— ·/);mode°dONLNdì‘/‡3)$ °dONLNdî‘3‡˛)*necessary to set the device to the desired°dONLNdø„<Ô‚( Z"depth (which may be passed as the °dONLNd·‡‚$)¶newDepth°dONLNdÈ„$Ôã)B parameter in a call to °dONLNd‡ãΔ)gSetDepth°dONLNd    „ΔÔÕ);).°dONLNd ˚<ù(#ZFurther Reference: &X&°dONLNdNR+
  119. •°dONLNd!`≤)Inside Macintosh°dONLNd1≤?)R, Volume V, Graphics Devices°dONLNdNN R(<l•°dONLNdP` j)4Designing Cards and Drivers for the Macintosh Family°dONLNdÑj ∑(<à, Second Edition°dONLNdï,<8E(TZ7Mountain Dew is a registered trademark of Pepsico, Inc. fiXfi
  121. (ÒZIGimmie Depth Or Gimmie Death (So You Want to be a Monitors Impersonator?)(Ò3) of 3ˇ